home *** CD-ROM | disk | FTP | other *** search
/ BMUG PD-ROM B4 / PD-ROM B4.iso / Utilities / Text and Speech / Alpha 5.3 / Help / Alpha Tcl Extensions < prev    next >
Text File  |  1993-01-30  |  17KB  |  319 lines
  1. ==============================================================================
  2. = Alpha's Additional Tcl Commands
  3. ==============================================================================
  4.  
  5. In this list of routines, text between '<' and '>' is a placeholder for a 
  6. required parameter, text between '[' and ']' is a placeholder for an 
  7. optional parameter, and the '|' signifies a choice of two alternatives. A 
  8. '+' signifies that the previous symbol can be present one or more times, 
  9. while a '*" means zero or more times. 
  10.  
  11. The following are Alpha-specific tcl routines:
  12.  
  13. • addMenuItem [-m] [-l <meta-characters>] <menu name> <item name> - Convert
  14.   item to menu form and add to specified menu. If '-m' specified, menu 
  15.   form conversion not done. The '-l' option allows you to use menu meta 
  16.   characters as text of menu items. If the '-l' option is used, the 
  17.   <meta-characters> string is interpreted for menu item attributes, and 
  18.   meta-characters in <item name> are included in the menu item text 
  19.   literally. For example: 
  20.       addMenuItem -m -l "/B" "Hello/C" 
  21.   would appear as the text "Hello/C" in the menu, and have "B" as its 
  22.   command equivalent.
  23. • alertnote message_string
  24.   This command will display message_string in a standard Macintosh alert box.
  25. • ascii (see bindings).
  26. • askyesno prompt
  27.   This command will display a Macintosh alert box with promptdisplayed 
  28.   with the push buttons Yes, No, Cancel. The command will return the 
  29.   string "yes", "no", or "cancel".
  30. • beep
  31. • bind  (see bindings)
  32. • blink <pos> - blink cursor at 'pos'
  33. • breakIntoLines <string> - return 'string' with 
  34.   carriage returns and spaces inserted to satisfy 
  35.   'leftFillColumn' and 'fillColumn' variables.
  36. • bringToFront <winName> - Bring named window to front.
  37. • cd [directory]
  38.   This command will set the current working directory to "directory". The directory 
  39.   argument may or may not end with a colon. The working directory is the directory 
  40.   in which file names that contain no colons (folders) will be located with file related 
  41.   commands. No argument means Alpha's home directory.
  42. • colors <fore red> <fore green> <fore blue> <back red> <back green> <back blue>
  43. • cp <fromName> <toName> [force]
  44.   This command will copy the file fromName and name the new file toName. If 
  45.   toName includes a path name that is different from the path in fromName, the copy 
  46.   will be made in a new directory (specified by toName). The copy can be made 
  47.   across volume (disk drives). The force option indicates that the copy should 
  48.   overwrite any existing file with the same name as toName. This command copies 
  49.   both data forks, and the Finder information.
  50. • createTMark <name> <pos> - create a temporary 'mark' 
  51.   at location 'pos'. 
  52. • ctime <time>
  53.   This command will return a UNIX time string of the format "Wed Feb 19 
  54.   22:43:36 1992". The parameter time is in Macintosh seconds, and would be the 
  55.   result of a now or file mtime command or the like.
  56. • deleteMenuItem [-m] <menu name> <item name> - Convert item to menu form 
  57.   and delete from specified menu. If '-m' specified, menu form conversion 
  58.   not done. 
  59. • deleteText <pos1> <pos2> - remove text between 'pos1' 
  60.   and 'pos2'
  61. • displayMode <mode> - Up to four characters of the 'mode' string are 
  62.   displayed in the status line at the bottom of a window.
  63. • dosc <-c 'sign' | -n appName> <-s string | -f fileName> [-t timeout]
  64.   Send a 'misc' 'dosc' AppleEvent. Options are the following:
  65.    -c 'sign' 
  66.            "sign" is a four-letter creator signature of a running application.
  67.    -n appName
  68.            "appName" is the name of a running application.
  69.    -s string
  70.            "string" is the text of a script to send to the other app.
  71.    -f fileName
  72.            "fileName" is the complete or relative pathname of a file the other 
  73.            application should execute.
  74.    -t timeout
  75.            "timeout" is the number of ticks Alpha should wait for a response. A 
  76.            timeout of "0" means wait forever.
  77.    -r
  78.            Do not wait for reply.
  79.    If neither of the '-c' and '-n' options is chosen, the PPC Browser is 
  80.    used. Either '-s' or '-f' must be chosen. Thus, you can have "Alpha 
  81.    5.02" and "Alpha 5.02 Copy" sending Apple events to each other, or they 
  82.    can send events to a remote server such as Apple's ToolServer. 
  83.  
  84. • echo <string> [<string>...] - echo the strings (used 
  85.   in shells).
  86. • edit <name> [-r] [-m] - Open a file in a new window. '-r' means open 
  87.   the file read-only. '-m' means omit the function titlebar menu and  
  88.   present only the marks titlebar menu, which is labeled with the 
  89.   contents of 'markLabel'.
  90. • get_directory
  91.   This command will display a standard Macintosh file dialog and request the user 
  92.   select a folder. The command will return the selected folder's full path name, or an 
  93.   empty string if the Cancel button was selected.
  94. • getenv <varname>
  95.   This command will return the value of the environment variable varname. 
  96.   Environment variables are initialized by reading the file •tclenv. The environment 
  97.   file has the format varname=value as in the following example:
  98.  
  99.     TERM=vt100
  100.     TCLINIT=::tcl:TclInit.tcl
  101.     TCLDEFAULT=
  102.     TEST=TEST
  103.     TCLPATH=::tcl:tclsh:tclsrc
  104.  
  105. • getfile <prompt>
  106.   This command will display an SFGetFile() and return the full path name of the 
  107.   selected file, or an empty string if CANCEL button was selected.
  108. • getfinfo <fileName>
  109.   This command will display the standard Macintosh file information in the form:
  110.   "'aeQL' 'QUIL' lvbsIdm 02/17/92 23:57:12 02/19/92 22:43:36 0,156 219 0".
  111.   The fields are the fdCreator, fdType, fdFlags, flCreationDate, flCreationtime, 
  112.   flModDate, flModTime, fdLocation.H,V, dataForlLength, rsrcForkLength, 
  113.   respectively. The fdFlags field uses characters to represent bits:
  114.     l/L    not locaked/Locked
  115.     v/V    visible/notVisible
  116.     b/B    not bundled/Bundled
  117.     s/S    not system/System
  118.     i/I    not initialized/Initialized
  119.     d/D    not desktop/Desktop
  120.     m/M    not sharable/sharable
  121. • getGeometry - return a TCL list containing the left 
  122.   edge of the current window, the top, the width, and
  123.   height.
  124. • getline <prompt> <default>
  125.   This command will display a Macintosh alert box with prompt displayed, a 
  126.   text edit field with default initially in the field, and with the push 
  127.   buttons OK, Cancel.. The command will return the text entered into the 
  128.   text edit field by the user, or an empty string if the user selected the 
  129.   Cancel button. 
  130. • getMainDevice - return a list containing the left, top, right, and 
  131.   bottom of the rectangle defining the main device.
  132. • getMark - return the current mark.
  133. • getPathName - prompt the user with an SFGetFile dialog and return 
  134.   complete pathname.
  135. • getPos - return the current insertion point
  136. • getSelect - return the currently selected text, if 
  137.   any.
  138. • getTMarks - Return a list of temporary marks. Each item of the returned 
  139.   list is a sublist containing the mark name, the complete pathname of the 
  140.   mark, and the start and finish of the selection named by the mark. The 
  141.   following is an example of the result: 
  142.  
  143.     {{temp1 External:file.c 1312 1315} {temp2 Internal:it.h 111 111}} 
  144.  
  145. • getText <pos1> <pos2> - return the text between 'pos1' 
  146.   and 'pos2'.
  147. • glob [-i] [-t <TYPE>] [-c <CRTR>]
  148.   The original glob provided by the UNIX version of tcl was not quite 
  149.   adequate for the more complex Macintosh file system. Issues such as 
  150.   invisible file handling, Finder type and creator filtering, and space 
  151.   handling in file names. Release 6 of tcl has dealt with the original 
  152.   problem with spaces in filenames, but the following options are provided 
  153.   to deal with additional Macintosh issues. 
  154.  
  155. Anyhow, the new glob now takes several options. They are:
  156.     -i    This option causes glob to list invisible files also.
  157.     -t TYPE    This option causes glob to only list file with the 
  158.         indicated Finder file typeTYPE. This option may be 
  159.         used with the -c option.
  160.     -c CRTR    This option causes glob to only list file with the 
  161.         indicated Finder file creatorCRTR. This option may 
  162.         be used with the -t option.
  163.         Also note that the original glob would skip dot files
  164.         (i.e., file names the begin with a period) 
  165.         in the listing, unless the pattern began with a period.
  166.         Tickle extends this concept one step further on the
  167.         Macintosh, and skips spot files (i.e., file names that 
  168.         begin with '•'), unless the pattern starts with a spot.
  169. • goto <pos> - goto the position 'pos'.
  170. • gotoTMark <name> - goto the temporary mark 'name'.
  171. • enableMenuItem <menuName> <item text> <on|off> - Either enable or 
  172.   disable the menu item of user menu 'menuName' that has text '<item 
  173.   text>'. Note that unless the menu is not only created, but also already
  174.   inserted, this command has no effect. 
  175. • icon [-f <winName>] [-c|-o|-t] [-g <h> <v>] - Having to do w/ 
  176.   iconifying windows. '-c' means close (iconify) window, '-o' open, '-t' 
  177.   toggle open/close, and '-g' moves the icon to horizontal position <h> 
  178.   and vertical position 'v'. Options are executed as they are parsed, so 
  179.   the '-f' option, if present, should always be first.
  180. • insertMenu <name> - insert the previously created user menu 'name' into 
  181.   the menuBar. 
  182. • insertText [-w <win name>] <text> [<text>]... - Insert 'text' at the current 
  183.   insertion point.
  184. • launch -f <name> - launch the named app into the background. Note that 
  185.   for some yet unexplained reason, some applications (MicroSoft Word) 
  186.   won't launch completely in the background. 'launch'ing such 
  187.   applications won't insert the application into any system menu that 
  188.   specifies running applications (although "About the Finder..." will 
  189.   list it. The only way to get to such an app is through Alpha's 
  190.   'switchTo', after which the application will finish launching. The '-f' 
  191.   option gets around this by launching the application in the foreground 
  192.   instead.
  193. • lineStart <pos> - return the position of the start of
  194.   the line 'pos' is on.
  195. • listpick [-p <prompt>] <list>
  196.   This command will display a dialog with the list displayed in a List Manager list. If 
  197.   the user presses the Cancel button, an empty string is returned. If the user selects 
  198.   the Open button, or double clicks an item in the list, that item will be returned.
  199. • lookAt [-w <name>] <pos> - return the 'pos'th character of the 
  200.   current file, or the file named by <name> if the '-w' option is specified.
  201. • markMenuItem <menuName> <item text> <on|off> - Either mark or unmark
  202.   the menu item of user menu 'menuName' that has text '<item text>'. 
  203.   Note that unless the menu is not only created, but also already
  204.   inserted, this command has no effect. 
  205. • matchIt <brace char> <pos> - Return pos of matching brace. Recognizes 
  206.   parenthesis, square brackets, and curly braces.
  207. • maxPos - returns the number of characters in the front
  208.   window.
  209. • menu [-n <name>] [-m] [-p <procname>] <list of menu items> - Defines a 
  210.   new menu named 'name' (if provided w/ '-n' option). The menu is not yet 
  211.   inserted into the menubar. The menu commands may be nested for 
  212.   heirarchical menus, see 'AlphaBits.tcl' for examples. Alpha massages the 
  213.   function names to make them look better in the menus. 
  214.   '-n <name>'    Name the menu. Not necessary for submenus.
  215.   '-m'            No menu form. If not supplied, each menu item is split into 
  216.                   words at each capitalized letter.
  217.   '-p <name>'     The tcl proc named by 'name' is called w/ the menu item's 
  218.                   contents as it's single argument when the item is chosen. If the 
  219.                   proc returns "normal" as its result, the menu item is executed as 
  220.                   if no proc had been specified.
  221. • message <string> - prints 'string' on the status line.
  222. • mkdir <name> - creates a directory (folder) named 
  223.   'name' in the current directory.
  224. • moveWin [win name] <left> <top> - moves current or specified window.
  225. • mtime <time> [long|short|abbrev]
  226.   Returns a date and time string using the Macintosh International Utilities. The 
  227.   long/short/abbrev specification corresponds to the date. These are the following 
  228.   formats:
  229.     short        3/16/92 9:20:46 PM
  230.     abbrev    Mon, Mar 16, 1992 9:20:49 PM
  231.     long        Monday, March 16, 1992 9:20:43 PM
  232. • mv <fromName> <toName> [force]
  233.   This command will move the file fromName to toName. If toName includes a path 
  234.   name that is different from the path in fromName, the file will be moved into a new 
  235.   directory (specified by toName). The move can not be made across volume (disk 
  236.   drives). The force option indicates that the move should overwrite any existing file 
  237.   with the same name as toName.
  238. • nextLineStart <pos> - return the position of the start 
  239.   of the next line after position 'pos'.
  240. • now
  241.   Returns the current time as Macintosh seconds. This is the number of seconds that 
  242.   have elapsed since Midnight Jan 1, 1904. Appropriate for input to ctime.
  243. • posToRowCol <pos> - converts from absolute position to row, col.
  244. • prompt <prompt> <default> [<name> <menu item>...] - prompt dialog to 
  245.   the user with a prompt string and a default value. The prompt dialog can 
  246.   optionally include a popup menu specified by 'name' and the succeeding 
  247.   strings. Selection of the popup menu items inserts the item text into the 
  248.   editable dialog item. 'Prompt' returns the value of the editable item. 
  249.   If the 'Cancel' button is selected, the tcl returns an error and your 
  250.   script will be stopped unless you execute the command from 'catch'.
  251. • putenv <varname> <value>
  252.   This command will set the environment variable varname to value.
  253. • putfile <prompt> <original>
  254.   This command will display an SFPutFile() and return the full path name of the 
  255.   selected file, or an empty string if CANCEL button was selected. Original is the 
  256.   default name displayed for the user.
  257. • pwd
  258.   This command will return the current working directory.
  259. • removeMenu <name> - remove menu 'name' from menubar.
  260. • removeTMark <name> - remove temporary mark.
  261. • replaceText <pos1> <pos2> [text]+ - replaces the text
  262.   between 'pos1' and 'pos2' with 'text', where 'text' can be any number 
  263.   of arguments.
  264. • rm <fileName>
  265.   This command will delete the file fileName.
  266. • rowColToPos <row> <col> - converts to abosolute position.
  267. • search [-f <num>] [-r <num] [-i <num>] [-m <num] [-n] [-l <limit>] <pattern> <pos> - 
  268.   Searches for 'pattern' from position 'pos'. The '-f', '-r', '-i', and 
  269.   '-m' options allow the 'forward', 'regExpr', 'ignoreCase', and 
  270.   'matchWord' internal variables to be set. The '-l' option allows a search 
  271.   limit to be set. The search fails if the a match is not found totally 
  272.   contained between 'pos' and 'limit'. The '-n' option specifies that a 
  273.   failed search still returns TCL_OK. However, the result of the call is 
  274.   then just an empty string. If the search succeeds, a list of two 
  275.   positions will be returned. The first is the starting position of the 
  276.   match, the second is one past the last character. 
  277. • select <pos1> <pos2> - selects the text between 'pos1' 
  278.   and 'pos2'.
  279. • selEnd - returns the end of the hilited selection, or 
  280.   the current insertion point if no text is selected.
  281. • sendToBack <winName> - Sent named window to back.
  282. • setfinfo <fileName> [-a flags] [-c fdCreator] [-t fdTypes]
  283.   This command will set the standard Macintosh file information. The flags setting 
  284.   must be of the same format as displayed by the getfinfo flag.
  285. • shadowVar <name> - Associates a Tcl variable with an Alpha variable of 
  286.   the same name. Writes to the Tcl variable automatically are copied to 
  287.   the Alpha variable.
  288. • sizeWin [win name] <width> <height> - sets size of current or specified window.
  289. • substituteVars <string> - Takes a single string and
  290.   substitutes for all variables inside it, regardless of
  291.   depth. Unfortunately, you currently need to make 'global var' 
  292.   declarations in the proc you call this for each 'var' that might need 
  293.   to be substituted in the string (see proc.tcl for examples).
  294. • switchTo <appName> - Switches to application 'appName'.
  295. • tclResult - displays a dialog showing the result of 
  296.   the last TCL evaluation.
  297. • ticks
  298.   Returns the current TickCount. Ticks are 60ths of a seconds. TickCount is the 
  299.   number of ticks since the Macintosh was started. The command:
  300.         puts stdout [expr "[ticks] / 60"]
  301.   will print the number of seconds since the Macintosh was booted.
  302. • traceFunc on <funcName> <winName> Trace 'funcName', send output to 
  303.                                     'winName'. 
  304.   traceFunc off                        Turn function tracing off.
  305.   traceFunc status                    Display current tracing status.
  306. • watchCursor - turns the cursor into a a watch cursor.
  307. • winNames [-f] - return a TCL list of all open windows. If '-f' option 
  308.   specified, complete pathnames are returned.
  309. • wrapText
  310. • xtclcmd [-f filename] <cmdname> [argument_list]...
  311.   This command will load the external command cmdname and pass it the argument 
  312.   list [ cmdname argument_list... ]. External command are code resources of type 
  313.   XTCL. They may be located in the resource fork of the tickle application, or they 
  314.   may be located in a file named XTCL File in the same directory as the tickle 
  315.   application. If the optional -f filename is included, the external command will first 
  316.   be loaded from filename before the other two files.
  317.   See the appendix for a detailed description of the external tcl command interface. 
  318.   See the accompanying sources for an example of writing an XTCL.
  319.